Subaccount Management
A Subaccount is a way to manage your clients by separating your main account (Avenia API Main Account or BA) from others.
The diagram shows that multiple accesses can manage subaccounts related to the main account.
Create Subaccount
When creating a Subaccount, you gain the ability to perform operations such as: KYC, OPERATIONS, BENEFICIARY BANK ACCOUNT, BENEFICIARY WALLETS, and other Avenia API features.
Endpoint
Fields
| Field | Type | Description |
|---|---|---|
accountType | string | Type related to this subaccount (INDIVIDUAL) |
name | string | Name to facilitate identification of this sub-account up to 64 characters |
allowedAccessIds | array of string | Optional. Accesses of your account that see only their allowed subaccounts and get this one too, such as the advisor in charge of the customer. At most 20. Any access that can create subaccounts may send it, and List Restricted Accesses returns the candidates. An access that is not from your account is refused with allowedAccessIds is invalid. |
Request body
{
"accountType": "INDIVIDUAL",
"name": "jane doe"
}
Request example
curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/sub-accounts" \
-H "Content-Type: application/json" \
-d '{
"accountType": "INDIVIDUAL",
"name": "jane doe"
}'
Without allowedAccessIds, a new subaccount stays hidden from every access limited to its allowed subaccounts, except the one that created it. An access in the list that sees every subaccount already sees the new one, and nothing changes for it.
Response
The response will include the ID linked to the created Subaccount.
{
"id": "c852df87-ac61-4259-8242-6451658dfedb"
}
Sub-accounts are permanent once created — deletion is not supported. DELETE /v2/account/sub-accounts/{id} returns 405 Method Not Allowed.
List All Subaccounts
To view all your Subaccounts, use the list endpoint with these parameters:
Fields
| Field | Type | Description |
|---|---|---|
name | string | Search for names containing specific characters |
cursor | string | Pagination cursor to advance through results |
Endpoint
Request example
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/sub-accounts"
Response
{
"cursor": "MTEwLTE3NDMwMjkzNTUyODE=",
"subAccount": [
{
"subAccountId": "2eea0102-dabe-4ab6-8707-0817aa52dfe4",
"mainAccountId": "3657c184-854c-4a71-98b0-9fc8e2960ba8",
"createdAt": "2025-03-27T09:59:59.099865Z",
"accountInfo": {
"id": "87b3ab56-463c-4207-ae31-4d2bd26dc66a",
"accountType": "INDIVIDUAL",
"name": "Ada Doe"
}
}
// ... other subaccounts
]
}
Find Subaccounts by Name
Turns subaccount names, such as a column of a spreadsheet, into subaccount IDs. A name matches regardless of case, accents and extra spaces, so jose doe finds José Doe.
Endpoint
Fields
| Field | Type | Description |
|---|---|---|
names | array of string | The names to look up, from 1 to 1000. |
Request body
{
"names": ["Ada Doe", "jose doe", "Jane Roe"]
}
Request example
curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/sub-accounts/resolve-names" \
-H "Content-Type: application/json" \
-d '{
"names": ["Ada Doe", "jose doe", "Jane Roe"]
}'
Response
results has one entry per name sent, in the same order, repeated names included. subAccounts holds the subaccounts with that name, newest first: none when the name is not found, more than one when subaccounts share it.
{
"results": [
{
"name": "Ada Doe",
"subAccounts": [
{ "id": "2eea0102-dabe-4ab6-8707-0817aa52dfe4", "name": "Ada Doe" }
]
},
{
"name": "jose doe",
"subAccounts": [
{ "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "name": "José Doe" },
{ "id": "16fd2706-8baf-433b-82eb-8c7fada847da", "name": "Jose Doe" }
]
},
{
"name": "Jane Roe",
"subAccounts": []
}
]
}
Only the subaccounts that List All Subaccounts returns to your access are searched, so a subaccount your access does not see is not found. The request only reads: a view-only access can make it. With a login (JWT), it still needs TOTP on the access, as every POST does — see When TOTP is required. Sending no names or more than 1000 returns 400 names is invalid, with extraInfo send from 1 to 1000 names.
Get Specific Subaccount
Retrieve details of a specific Subaccount using its ID.
Endpoint
Request example
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/sub-accounts/SUBACCOUNT-ID-HERE"
Response
{
"subAccountId": "2eea0102-dabe-4ab6-8707-0817aa52dfe4",
"mainAccountId": "3657c184-854c-4a71-98b0-9fc8e2960ba8",
"createdAt": "2025-03-27T09:59:59.099865Z",
"accountInfo": {
"id": "87b3ab56-463c-4207-ae31-4d2bd26dc66a",
"accountType": "INDIVIDUAL",
"name": "Ada Doe"
}
}
Conclusion
You can now fully utilize Subaccount capabilities. Remember to include the subAccountId parameter in endpoints that allow Subaccount operations.